====== Toolchain IDE Setup ======
    for MIOS application development on Windows

\\
\\
**The technical jargon:**\\
This is //Part THREE of THREE// in a walkthrough on the process of developing [[MIOS]] Applications, primarily in C, [[how_to_mix_c_and_asm|but also in ASM]] utilising the [[http://www.ucapps.de/mios_c.html|MIOS C Wrapper]] or Microchip's [[http://www.microchip.com/|MPASM]]. The platform used will be [[http://www.codeblocks.org|Code::Blocks IDE]] on[[http://microsoft.com/windowsxp|Microsoft Windows XP]], and the applications will be built for both [[mios_c_simulator_-_debugger|AC-Sim (AudioCommander's C Simulator)]] compiled with [[http://gcc.gnu.org|GCC]] for [[http://www.mingw.org|MinGW]], and for the [[home#mbhpmidibox_hardware_platform|MIDIBox Hardware Platform (MBHP)]] compiled for [[http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=2042&param=en020453&pageId=74|PIC18F]] with [[http://sourceforge.net/projects/sdcc|SDCC]], assembled with [[http://sourceforge.net/projects/gputils|GPUtils]], using [[http://www.activestate.com|ActiveState]] [[http://www.activestate.com/Products/ActivePerl/?mp=1|ActivePerl]] to generate, and parse files for, the DOS-Console-based make batch file scripts, and [[http://miosstudio.midibox.org|MIOS Studio]] will be used for debugging on MBHP.

**Enough of that.**\\
You have probably come here from [[windows_toolchain_asm_acsim|Part 2]]. This third part of the tutorial can also be skipped completely if you wish. It contains setup instructions for two components of the toolchain. Select the ones you need, skip the ones you don't. Here's my advice:

  * Code::Blocks - It's an IDE. If you don't know what that entails, then just trust me that you will like it ;)
  * GDB - The GNU De-Bugger - If you want to make use of AC-Sim (you will have decided this previously in this tutorial) you should install the GDB to assist you in the debugging process. If you are not going to use Code::Blocks, your IDE may use a different debugger, so you won't need this. 
If you are not sure, and you have a few meg of diskspace to spare, I would recommend that you install this now, as Code::Blocks will automatically detect it's presence, which makes setup simple.

\\
\\



====== GDB (GNU DeBugger) ======
GDB is used to debug apps and is a must-have for MIOS development.

  * [[http://downloads.sourceforge.net/mingw/gdb-6.3-2.exe?use_mirror=jaist|Download the installer]]. This Link is for GDB 6.3.2, You may find a newer version on [[http://sourceforge.net/project/showfiles.php?group_id=2435&package_id=20507|the SourceForge page]] 
  * Install, taking the same default install path as MinGW (see [[windows_toolchain_asm_acsim#mingw|Part 2]]).
\\
\\
\\


====== Code::Blocks IDE ======
Code::Blocks is a free yet powerful IDE. Highly recommended on Windows.

===== Install =====

The full Code::Blocks installer package is //not recommended //. We need to manually install and configure [[http://www.gnu.org/software/gdb/|GDB (GNU DeBugger)]] and [[http://www.mingw.org|MinGW]], which contains [[http://gcc.gnu.org|GCC]] - the GNU C Compiler. **It is strongly recommended that you install these PRIOR to installing Code::Blocks** If you've been following the three-part tutorial, then you're about right.



===== Code::Blocks =====
For our purposes, CodeBlocks latest nightly build version should be installed.

//If there is an existing version installed, then delete the share\ dir, for example C:\Program Files\CodeBlocks\share\*.* before upgrading//
\\
  * Get link for Nightly Build from the [[http://forums.codeblocks.org/index.php?board=20.0|CB Forum]]
  * Unzip downloaded file to Program Directory, for example C:\Program Files\CodeBlocks\, and overwrite where prompted.
:!: Note that these links sometimes change! They are usually (always!) in the first post of the thread for the Nightly Build. Get them from there!!
  * Download a [[http://prdownload.berlios.de/codeblocks/wxmsw28u_gcc_cb_wx284.7z|patched wxwidgets dll]] :!: and extract to the CodeBlocks Program Directory, for example C:\Program Files\CodeBlocks\
  * Start Code:Blocks. If it generates an error about mingwm10.dll missing, ensure the above path variables are set. If you are SURE that they are and the file is missing, download it from [[http://prdownload.berlios.de/codeblocks/mingwm10.7z|here]] :!: and copy the .dll to your program directory\\

  * Code:Blocks will detect and configure installed compilers. It should find 'GNU GCC Compiler' if you installed MingW, and 'SDCC Compiler' if you installed SDCC (WHICH YOU SHOULD HAVE!). Accept defaults.


===== Configure =====
In order to use the [[http://www.gnu.org/software/gdb/|GDB (GNU DeBugger)]] debugging features of Code::Blocks with [[mios_c_simulator_-_debugger|AC-Sim (AudioCommander's C Simulator)]] you need to configure [[http://gcc.gnu.org|GCC]] to produce debugging symbols when compiling as follows:

  * Select the menu 'Settings... Compiler and Debugger...'
  * Select 'Global Compiler Settings' in the pane on the left
  * In the box labelled 'Selected compiler', select 'GNU GCC Compiler'
  * Select the tab labelled 'Compiler Settings' and then the tab labelled 'Compiler Flags'
  * From the dropdown box labelled 'Categories:', select <All categories>
  * Tick the box labelled 'Produce debugging symbols  [-g]' (Sometimes there's no box, just click in the space to the left of the text and you'll see the tick.
  * Click OK.

This should be all that is needed to have the application itself ready to go!
\\
\\




===== Project Setup =====

Full instructions are below, but you may jump to the required section based on your requirements:
\\


==== Project Setup - New Application ====

If you are creating a new application, you can simply {{cb_sdcc_skeleton.zip|download the MIOS SDCC Skeleton Application Template}}, extract it to your template directory, and start with that, and none of the below steps are necessary. This zip file does not change any of the functionality of the normal SDCC Skeleton App, so you can use it as normal, as well as with C::B. Here is a walkthrough:

  * {{cb_sdcc_skeleton.zip|Download the MIOS SDCC Skeleton Application Template}}
  * Extract the contents of the zip to your user template directory. It will be C:\Documents and Settings\<your username>\Application Data\codeblocks\UserTemplates
  * In Code::Blocks, Select 'File... New Project'
  * Select the tab labelled 'User Templates', and double-click the project named 'CB SDCC Skeleton'
  * Writing your code is up to you but once you're done, jump to the section on Compiling and Debugging for either [[#ac-sim_simulator|AC-SIM]] or [[#MBHP|MBHP]]

//You may want to visit the AC-Sim page to update your Simulator files!//
\\

==== Project Setup - Existing Application or Skeleton Creation ====

A C::B Project can be setup from either an existing MIOS C Application or the SDCC_Skeleton App as follows. You should have your application/skeleton in a dedicated folder.
\\

==== Create Empty Project ====
  * Copy all files from either the [[http://ucapps.de/mios/sdcc_skeleton_v1_9a.zip|C Skeleton]], or your app, to a directory where you would like to store the project. *
  * Start Code::Blocks
  * Open a new project ('File... New Project')
  * Click 'Console Application' from the list. Click 'Go'.
  * In the box labelled 'Project Title', give your app a name. For 'Project Path', browse to the directory containing your MIOS Application or Skeleton *, and add the name of your Project. Click 'Next'.
  * Ensure 'GNU GCC Compiler' is selected. Click 'Next'
  * If you are prompted to select a language to use, select 'C' (not C++). Click 'Finish'.
\\


==== Add Application files to project ====

  * When you first create the project, C::B will automatically create a 'Hello World' application. This main.c needs to be deleted. Right-Click it, and choose 'Remove from project'.
  * Now open up Widows Explorer (aka 'My Computer'), browse to your project directory* and delete that file for good. It would get in the way when you...
  * Move all of your skeleton files into the C::B Project directory* (Where you see a *.CBP file you specified earlier).
  * Create an empty text file in that directory, named "main.h". You will need this file for the AC-Sim setup later on, and probably in your own application anyway. It won't hurt.
  * Select 'Project... Add Files', Select All of the source code files in your new Skeleton directory*, Click 'Open'.
  * If you are prompted to select which build target should be used, click 'Deselect All' and click OK until the files are all added.
  * Double-click the tree branch in the far left pane labelled "Sources". you should see your main.c file in there. Double-click it to open it for editing.
  * Immediately after the copyright notice, insert this code:
\\
<code c>
#include "main.h"
</code>
  * Right Click the file's name in the tab bar, and select 'Close'. When you are prompted to save the file, save it.

\\

==== Configure Build Targets ====

=== AC-SIM Build Target ===
//You may skip this section if you do not need to use the simulator//

  * Ensure AC-SIM files are added to the project. Follow the instructions at [[mios_c_simulator_-_debugger#setup_guide|the AC-Sim WIKI page Setup Guide]]
  * Select 'Project... Properties', Select the 'Build Targets' tab, you should see two targets preconfigured ('Debug' and 'Release'. Debug will be used for AC-Sim, and Release for MBHP (PIC))
  * Select the target 'Debug'
  * In the box labelled 'Selected build target options', select 'Console Application' from the drop-down list labelled 'Type'
  * In the box labelled 'Selected build target files', Click 'Toggle Checkmarks' to uncheck all of the files. Now, Tick ONLY 'ACSim_Console.c', 'ACSim_mios.c' and 'ACSim_Toolbox.c'.

=== MBHP Build Target ===
//You should always perform the following sections to build the application for MBHP(your MIDIbox!)//

  * Returning to 'Project... Properties', 'Build Targets' tab, select the build target 'Release'
  * In the box labelled 'Selected build target options', select 'Commands Only' from the drop-down list labelled 'Type'
  * In the box labelled 'Selected build target files', Click 'Toggle Checkmarks' to uncheck all of the files. Now, Tick ONLY 'main.c' (even if you have other files to compile. That's done by the make script)
  * Click 'OK' to close project properties

  * Select 'Project... Properties', Select the 'Targets' tab (Yes, again. It is necessary to apply the previous settings first)
  * Select target 'Release', click 'Build Options'
  * In the box labelled 'Selected Compiler' Select 'SDCC Compiler' from the dropdown list (until this point both targets will be using C::B's default of GCC), Click 'OK' and return to the 'Targets' tab. If you receive a warning recommending you to "fully rebuild...", that is normal. Click OK.
  * In the box labelled 'Selected build target files' (bottom right), select file 'main.c' and then click 'Selected File Properties'
  * Select the 'Advanced' tab, in the box labelled 'Custom Build', Select 'SDCC Compiler' from the dropdown list labelled 'For this compiler'
  * Tick 'Use Custom Command to build this file'
  * Type into the textbox "make.bat"
  * Click OK
  * Click OK
\\

==== MIOS-Specific SDCC Libraries ====

TK says:
If multiplications, divisions, pointer operations, etc. are used in the .c code, the linker may fail due to missing functions, which are part of the "libsdcc.lib" library. The error message will be:

  Linking project
  lib/libsdcc.lib: No such file or directory
  ERROR!

The common library for pic16 derivatives is not compatible to MIOS, therefore I've created a special one. [[http://www.ucapps.de/mios_c.html|Click here for more information]]

  * Download the [[http://www.ucapps.de/mios/mios_libsdcc_v2_5_0.zip|MIOS-Specific SDCC Libraries]]
  * In Windows Explorer, create a 'lib' directory within the root directory of your project
  * Copy the 'libsdcc.lib' file from the above zip file into this directory
  * Open the "project.lkr" file of your project (can do this in Code::Blocks if you like, it will be listed under 'Others' in the project tree) and add following line below the "LIBPATH" entry:

''
FILES lib/libsdcc.lib
''
\\

At this point, I highly recommend selecting 'File... Save Project as user template', then you can use it as a quick starting point for all your awesome projects :)

\\
\\
\\
\\

===== AC-Sim Simulator =====

==== Setup ====

Follow the instructions at [[mios_c_simulator_-_debugger|the AC-Sim WIKI page]]

==== Compile ====

Select the 'Debug' target, Click 'Build', and you're done!

==== Debug ====

Follow the instructions at [[mios_c_simulator_-_debugger|the AC-Sim WIKI page]]


===== MBHP =====

==== Compile ====

Select the 'Release' target, Click 'Build', and you're done!

==== Debug ====

Well, that's up to you! 
\\ 
\\
\\

\\
\\
\\
====== Part 3 Complete ======
**If you made it this far**, you should be writing code right now! :D
Stay tuned for tutorials on burning PICs with PICPGM, and uploading MIOS and apps with MIOS Studio.
\\
\\
